Prograph's AppleTalk primitives provide a vastly simplified interface for accomplishing the most common network tasks - registering on the network, finding out what other nodes are out there on the network, and sending textual data between programs on the network. It is not necessary to read Inside Macintosh to use these primitives.
A SPECIAL NOTE ABOUT ATP: The AppleTalk Transaction Protocol is a protocol for delivering data between nodes on an AppleTalk network. The AppleTalk Manager toolbox calls are described in Inside Macintosh . Detailed information about AppleTalk protocols is available in Inside AppleTalk.
Loading AppleTalk Primitives
AppleTalk primitives are stored in the Communication Primitives file, located in the Disabled Primitives folder, a subfolder in the Prograph Extensions folder. These primitives are not initially loaded with Prograph Classic, as packaged.
NOTE: The Communication Primitives file also contains the Serial Port primitives.
In order to use the AppleTalk primitives, shut down Prograph and move the Communication Primitives file into the Prograph Extensions folder. You may have to increase Prograph's minimum memory allocation using Finder's Get Info dialog. The AppleTalk primitives are enabled the next time you start Prograph.
Using AppleTalk Primitives *250*
Network-aware programs are either clients, server programs, or both. All of these must call ATP-Open and NBP-Open sometime after starting up, and before using any other AppleTalk primitives. The next step is usually to call NBP-Register to make the program's name and type known to other programs on the network. Note that the program type can be any string you like. It allows you to later query the network to find out all programs of a certain type that are running on the network.
Once registered, server programs use ATP-Get-Request periodically (i.e. at idle time) to check for client-side requests being sent. When a request is received, the server uses ATP-Send-Response to reply to the client. On the other side, client programs wait for some user action or other event to precipitate sending a request to a server with ATP-Send-Request. After the request is sent, the client must check periodically for the server's response with ATP-Get-Response.
The contents of the request and response strings are entirely up to the client and server programs. Usually you would define your own “code words” for the requests and responses. If you are working with an existing server program, it should have documented which requests it understands, and the format of the responses.
AppleTalk Errors *251*
Every AppleTalk primitive returns an integer error code. Zero means success; otherwise, an error has occurred. Error numbers may be one of those documented in Inside Macintosh, or one of the following:
Error Number Description
1 The AppleTalk protocol is already active
2 Both NBP and ATP must be open
3 The port is not configured for AppleTalk
4 Unable to open AppleTalk because AppleTalk is inactive
5 The Correct versions of the AppleTalk drivers are unavailable
6 Unable to execute server only primitives from a client
7 Unable to execute client only primitive from a server
8 Unable to locate entity
9 Unable to respond to the client
10 Attempting to register on AppleTalk under more than one name
11 Unknown error
12 Memory error
13 Entity not found
_________________________________________________
 
ATP-Close *251*
Output types: integer
Description: Closes AppleTalk under ATP. If you have called ATP-Open, you must call ATP-Close before quitting your application.
See also: ATP-Open
_________________________________________________
 
ATP-Get-Request *252*
Input type: boolean
Output types: list; string; integer
Description: Used by server-side applications to check whether a request has been sent by a client. If AutoRespond is true, a response will automatically be sent, containing the default message “OKAY”. Sender is a list of three integers which identify the sender. This list should be passed into ATP-Send-Response.
See also: ATP-Send-Response
_________________________________________________
 
ATP-Get-Response *252*
Output types: list; string; integer
Description: Used by client-side applications to check for a server's response after the client has sent a request. If no responses are available, Message and Sender are NULL. Otherwise, Sender is in the form of a list of three strings: (Name Type Zone).
See also: ATP-Send-Request
_________________________________________________
 
ATP-Open *252*
Input types: string; boolean
Output types: integer
Description: Opens AppleTalk under ATP. Must be called before using any of the other ATP primitives. NodeType may be “server”, “client” or “both”. If SelfSend is TRUE, the node is able to send to itself.
See also: ATP-Close
_________________________________________________
 
ATP-Send-Request *253*
Input names: Servers; Request; [Count; Interval]
Input types: list of ( Name [Type [Zone]] ); string; [ integer; integer ]
Defaults: Count = 2; Interval = 8; Type = "=" (current type); Zone = "*" (all zones)
Output types: integer
Description: Used by client-side applications to send a Request to a list of Servers. Each server identifier in the list is itself a list of one to three strings: (Name [Type [Zone]]). Use NBP-Lookup to obtain a list of which servers are available on the network. A value of “*” for Type means the request will be sent to all registered applications; “=” means it will be sent to applications with the same type as the sending application only. A value of “*” for Zone means all zones; “=” means the current zone only. Count is the number of retries. Interval is the number of seconds between retries.
Input types: list of integer; string; [ integer; integer ]
Defaults: Count = 2; Interval = 8
Output types: integer
Description: Used by a server-side application to send Response to Client. Client is the list of integers returned as the Sender by ATP-Get-Request. Count is the number of retries. Interval is the number of seconds between retries.
See also: ATP-Get-Request
_________________________________________________
 
NBP-Close *254*
Output types: integer
Description: Closes AppleTalk under NBP. If you previously called NBP-Open, you must call NBP-Close before quitting your application.
Defaults: Type = "=" (current type); Zone = "*" (all zones); Count = 2; Interval = 8
Output types: integer
Description: Confirms that a node is still on the network. Confirms the existence of Name of Type in Zone. Count is the number of retries. Interval is the number of seconds between retries. If node is confirmed, Error is 0; otherwise, Error is 13.
Defaults: Type = "=" (current type); Zone = "*" (all zones); HowMany = 100; Count = 2; Interval = 8
Output types: list; integer
Description: Finds out what other entities are on the network. Finds a maximum of HowMany entities of type Type in zone Zone. Count is the number of retries. Interval is the number of seconds between retries. Names is a list of entities found; each entity takes the form of a list of strings( Name Type Zone ).
See also: NBP-Confirm
_________________________________________________
 
NBP-Open *255*
Output type: integer
Description: Opens AppleTalk under NBP. Must be called before using any of the other NBP primitives.
Defaults: Name = User Name as entered in the Sharing Setup Control Panel; Type = “=”; Zone = “*”; Count = 2; Interval = 8; Verify = FALSE
Output types: integer
Description: Register the Name and Type on the AppleTalk network under NBP. Count is the number of retries. Interval is the number of seconds between retries. If Verify is TRUE, Name must be unique to the network.
